Convert Registry entry

Define how a document is converted from one format to another when a document is added to the Multimedia repository.

The Convert Registry entry provides a mechanism for converting one document format to another. As each conversion from one document type to another is defined as a separate Registry entry, providing a new conversion is simply a matter of adding a new Convert Registry entry.

Note: A Convert Registry defines the mechanism by which one document format is converted into another format. It does not make the conversion available to a user / group. A Documents Registry entry is then required to make the conversion available to users / groups.

The conversion framework supports three types of filters:

  • Client-side filters: document conversion carried out by a client-side (Windows) program
  • Client-side DDE filters: document conversion carried out by client-side (Windows) DDE server
  • Server-side filters: document conversion carried out by server-side program

Each conversion translates from a start format to an end format; for example it is possible to start with a Word document and end up with an HTML document. For each start and end format entry any one of the above filter types may be used.

Documents in the Multimedia module that are formatted as HTML, RTF or TEXT (those with a MIME type of text/html or text/plain) are automatically indexed and fully searchable.

When a document is added to the Multimedia module it is possible to have alternative document formats generated automatically by the System. A Documents Registry entry specifies which document types are automatically created when a document is added to the Multimedia module. The Convert Registry entry specifies how to convert one document type to another.

With this mechanism, documents can be converted into an indexable format and their contents made fully searchable.

See How do I search attached documents for more details.

Usage

This Registry entry can be assigned to users, groups and system-wide:

Key User Group System
Key 1 User Group System
Key 2 user group Setting
Key 3 Setting Multimedia
Key 4 Multimedia Convert
Key 5 Convert handle
Key 6 handle fileext
Key 7 fileext filtertype
Key 8 filtertype  
Value options
User user Setting Multimedia Convert handle fileext filtertype options
Group group Setting Multimedia Convert handle fileext filtertype options
System Setting Multimedia Convert handle fileext filtertype options

where:

handle

is a document handle used to identify the document type being converted (the start format).

A document handle is a label that is used to identify a document format. For example, the document handle for an HTML file is HTMLFile. The handle is used in place of a document extension to tie a file to a given piece of software.

Using the document handle it is possible to set up different conversion Registry entries for documents with the same file extension. For example, if MS Word is installed on a computer, the document handle for .doc files is Word.Document.8. If WordPad is installed rather than MS Word, the document handle for .doc files will be Wordpad.Document.1. As the handles are different, even though the file extension is the same, different conversion filters can be set up. This allows filters to be set based on the software installed on a user's machine.

To determine what the handle is for a given file type, it is necessary to look in the Windows Registry. The handle is the (Default) Registry value for the Registry key:

\HKEY_CLASSES_ROOT\fileextension

e.g. for a file extension of .aif, consulting the Windows Registry for the value of (Default) for \HKEY_CLASSES_ROOT\.aif gives the handle AIFFile:

Windows Registry Editor

Similarly, checking the file extension for .html (or .htm) gives a value of htmlfile; .txt yields txtfile.

It is important to remember that the document handle is used to determine how a document is translated from one format to another. For example, converting a .doc file on a machine that has MS Word installed (with a document handle of Word.Document.8) to an HTML file (with a file extension of html), EMu Registry entries that would apply would be:

Key User Group System
Key 1 User Group System
Key 2 user group Setting
Key 3 Setting Multimedia
Key 4 Multimedia Convert
Key 5 Convert Word.Document.8
Key 6 Word.Document.8 html
Key 7 html filtertype
Key 8 filtertype  
Value options

If the same conversion was to take place on a machine that has WordPad installed rather than MS Word, the following Registry entries would apply:

Key User Group System
Key 1 User Group System
Key 2 user group Setting
Key 3 Setting Multimedia
Key 4 Multimedia Convert
Key 5 Convert Wordpad.Document.1
Key 6 Wordpad.Document.1 html
Key 7 html filtertype
Key 8 filtertype  
Value options

Note: When installing new conversion Registry entries it is important to make sure the correct document handle is used to specify the original document format. It is also worth considering what software may be installed that can perform the conversion. If a Registry entry cannot be found for translating a document, the conversion fails and the required document format is not produced.

fileext

is the file extension of the document to be produced without the leading dot (the end document).

filtertype

indicates what type of filter is to be used. Allowable values are:

  • DDE

    A client-side DDE filter uses the Microsoft Dynamic Data Exchange mechanism to convert a document to a new format. DDE allows a program to be invoked and commands sent to it to be executed. Using this technology it is possible to "drive" an application from within EMu. For DDE to function a client/server setup is required. EMu operates as a client connecting to a DDE server. The server must support the Execute transaction.

    An example of a DDE server is MS Word. In order to translate a document from Word's internal format (.doc) to HTML it is possible to invoke Word, open up the file to be translated and perform a Save As... in HTML format, then close the original document. Similarly the Save As... facility could be used to generate TEXT and RTF documents.

    DDE uses an Application label to determine which DDE Server should be executed. The Application label is determined from the Windows Registry. For example, the Application label for Microsoft Windows is WinWord. Within an application a Topic is set to determine what part of the application is to be used. All DDE servers must support the System Topic. Using the Application and Topic settings it is possible to invoke a DDE server and prepare it to execute commands. EMu Registry entries suitable for setting the Application are:

    Key User Group System
    Key 1 User Group System
    Key 2 user group Setting
    Key 3 Setting Multimedia
    Key 4 Multimedia Convert
    Key 5 Convert handle
    Key 6 handle fileext
    Key 7 fileext DDE
    Key 8 DDE Application
    Key 9 Application  
    Value application

    and the Topic:

    Key User Group System
    Key 1 User Group System
    Key 2 user group Setting
    Key 3 Setting Multimedia
    Key 4 Multimedia Convert
    Key 5 Convert handle
    Key 6 handle fileext
    Key 7 fileext DDE
    Key 8 DDE Topic
    Key 9 Topic  
    Value topic

    Note: To determine the Application and Topic values required for a given DDE server, it is necessary to consult the server documentation.

    Once the server has been invoked it is possible to send it a command for execution. The format of the command varies from server to server. In essence the command should open up the original file, save it in the required format and close the original file. The format of a suitable Command Registry entry is:

    Key User Group System
    Key 1 User Group System
    Key 2 user group Setting
    Key 3 Setting Multimedia
    Key 4 Multimedia Convert
    Key 5 Convert handle
    Key 6 handle fileext
    Key 7 fileext DDE
    Key 8 DDE Command
    Key 9 Command  
    Value command

    The command is a sequence of instructions sent to the DDE server for execution. As for all commands, %1 and %2 are replaced with the input and output file respectively.

    The final setting allows a delay to be set after the command has finished being executed. Some DDE servers may indicate that the command has completed before the output file is ready for use by EMu (this is typically the case if EMu cannot open the generated file). The Registry entry for the delay is:

    Key User Group System
    Key 1 User Group System
    Key 2 user group Setting
    Key 3 Setting Multimedia
    Key 4 Multimedia Convert
    Key 5 Convert handle
    Key 6 handle fileext
    Key 7 fileext DDE
    Key 8 DDE Wait
    Key 9 Wait  
    Value seconds

    where seconds is the number of seconds to delay after the server has finished executing the command and before EMu tries to access the output file. If the Registry entry does not exist, a default value of 10 seconds is assumed. If EMu cannot access the output file after the translation, increasing this value may solve the problem.

    The following Registry entries could be used to provide translation from an MS Word document to an HTML document:

    Key System System System System
    Key 1 System System System System
    Key 2 Setting Setting Setting Setting
    Key 3 Multimedia Multimedia Multimedia Multimedia
    Key 4 Convert Convert Convert Convert
    Key 5 Word.Document.8 Word.Document.8 Word.Document.8 Word.Document.8
    Key 6 HTML HTML HTML HTML
    Key 7 DDE DDE DDE DDE
    Key 8 Application Topic Wait Command
    Value WinWord System 20 [FileOpen("%1")][FileSaveAs("%2", ConverterLookup ("HTML"))][FileClose(0)]

    All the above Registry entries should appear one per line. The Command entry is a set of VBA commands executed by Word to open the original document, save it as HTML and then close the original document. Note that if Word is already running, DDE will not start a new instance, rather it will use the existing one.

  • Command

    A client-side filter is a program executed on a Windows machine to convert a document from its original format into another format. EMu will run the filter and wait for it to complete. Once completed, EMu uses the output file as the translated document. The format of the Registry entries for client-side commands is:

    Key User Group System
    Key 1 User Group System
    Key 2 user group Setting
    Key 3 Setting Multimedia
    Key 4 Multimedia Convert
    Key 5 Convert handle
    Key 6 handle fileext
    Key 7 fileext Command
    Key 8 Command  
    Value command

    When a client-side filter is run, EMu creates a temporary file with the correct file extension (as specified by the fileext value). The temporary file is used as the output file into which the translated document is to be placed. The format of the command is the name of the program to perform the conversion along with any associated options and arguments. Two place-holders may be used in the command:

    • The first is %1, which is replaced with the full path to the input file (the file to be translated).
    • The second is %2, which is replaced with the name of the file into which the output is to be placed.

    For example, we have developed a VBA script that can convert an HTML document into a text document. The script takes two arguments. The first is the name of the HTML document to be converted and the second is the name of the output file into which the text is to be placed. A suitable Registry entry would be:

    Key System
    Key 1 System
    Key 2 Setting
    Key 3 Multimedia
    Key 4 Convert
    Key 5 HTMLFile
    Key 6 txt
    Key 7 Command
    Value MyScript %1 %2

    where:

    HTMLFile

    is the document handle for HTML files.

    txt

    is the file extension to be generated.

    When the command is executed, %1 and %2 are replaced with the input file and output file respectively. Note that EMu will suspend execution until the filter has completed running. If the output file does not exist after the filter has finished, the translation is deemed to have failed and the conversion is aborted.

    As a special case the command may be the keyword None. In this case the input file is simply copied to the output file and an external filter is not invoked.

  • Server Command

    A server-side filter is very similar to a client-side filter except that the command is executed on the EMu server. Using server-side filters will allow the translation software to be installed on one machine (the server) while being accessible to all users (clients). Suitable Registry entries are:

    Key User Group System
    Key 1 User Group System
    Key 2 user group Setting
    Key 3 Setting Multimedia
    Key 4 Multimedia Convert
    Key 5 Convert handle
    Key 6 handle fileext
    Key 7 fileext Server Command
    Key 8 Server Command  
    Value command

    The format of the command is exactly the same as for client-side filters. In other words it is the program to perform the translation along with its options and arguments. Also the place-holders %1 and %2 are replaced with the input and output file respectively. When a server-side filter is invoked, EMu copies the original file from the client machine to a temporary area on the server. The command is then executed on the server. Once the command has completed, the output file is copied back from the server to the client machine for use.

    Assume that a filter called /usr/local/bin/pdftotext is installed on the EMu server and it can convert PDF files into text. The filter takes some options and two arguments, namely the input and output files respectively. A suitable Registry entry would be:

    Key System
    Key 1 System
    Key 2 Setting
    Key 3 Multimedia
    Key 4 Convert
    Key 5 AcroExch.Document
    Key 6 txt
    Key 7 Server Command
    Value /usr/local/bin/pdftotext -eol dos %1 %2

    where:

    AcroExch.Document

    is the document handle for PDF files.

    Note: The document handle may not necessarily be AcroExch.Document in your environment - this will depend on the application installed to read PDF documents. You would identify the handle by checking the Windows Registry entry \HKEY_CLASSES_ROOT\.pdf

    The command executed on the server is invoked within a UNIX shell (/bin/sh) so any valid shell syntax may be used. If an error message is sent to STDERR, the filter is deemed to have failed and the translation is aborted.

    Note: There is also a pdftohtml filter that operates in the same manner.

options

depend on the filtertype selected (e.g. for a command filter the name of the program to invoke).

The three filter types with their supported options are detailed in the following pages.

Note: Although Registry entries may be set on a user or group basis, the System format is generally used.